Google Forms APIがv1になったのでAPIを使ってフォームを作ってみる
先日GoogleのForm APIがv1になり、GoogleWorkspaceのプラットフォームに加わったと発表がありました。
APIによってフォームの作成や編集を自動化、フォームの返答を検知してなんらかのワークロードのトリガーとしたりリアルタイムのダッシュボードを開発したりするといったユースケースに使えるとのことです。
実際に実行してフォームを作成していこうと思います。
やってみる
Forms APIのサービスはforms.googleapis.comで、APIのルートURL(サービスエンドポイント)はhttps://forms.googleapis.comです。
Google公式ではクライアントライブラリを使ってアクセスすることを推奨していますが、 今回はAPIs Explorerを使って実行していきます。
フォームの新規作成
新規のフォームを作成します。
HTTPリクエスト : POST https://forms.googleapis.com/v1/forms
フォーム作成時は、タイトルのみが必要で、他の項目を入れるとエラーになりました。
エラー内容:
{
"error": {
"code": 400,
"message": "Only info.title can be set when creating a form. To add items and change settings, use batchUpdate.",
"status": "INVALID_ARGUMENT"
}
}
フォームの内容はinfoオブジェクトのタイトルのみを指定して空のフォーム作成後にforms.updateで更新する必要があります。
infoオブジェクトの中身
フォームのタイトルと説明
{
"title": string, // 回答者に表示されるフォームのタイトル
"documentTitle": string, // Driveで表示されるドキュメントのタイトル
"description": string // フォームの説明文
}
リクエスト本文の例)
{
"info": {
"title": "サンプルフォーム"
}
}
レスポンス本文の例)
Create APIを実行後、responderUriに記載されているURLにアクセスすると空のフォームが表示されるはずです
フォームのアイテムを追加
新規フォームを作成後、フォームの中身を構築します。
createを実行して返ってきたformIdが必須のパラメータとなっています。
HTTPリクエスト : POST https://forms.googleapis.com/v1/forms/{formId}:batchUpdate
リクエスト本文
{
"includeFormInResponse": boolean, // 応答で更新バージョンを返すかどうか
"requests": [
{
object (Request) // 更新内容
}
],
"writeControl": {
object (WriteControl) // 書き込み要求の実行方法を制御
}
}
requestsに更新内容を記述していきますが、以下の種類が指定できます。
- updateFormInfo
- フォームの情報を更新(Infoオブジェクト)
- updateSettings
- フォームの設定を更新(FormSettingsオブジェクト)
- createItem
- 新しいアイテムを作成(ItemオブジェクトとLocationオブジェクト)
- moveItem
- アイテムを指定した場所に移動(Locationオブジェクト)
- deleteItem
- アイテムを削除(Locationオブジェクト)
- updateItem
- アイテムを更新(ItemオブジェクトとLocationオブジェクトとFieldMaskオブジェクト)
WriteControlは書き込み要求の実行方法を制御と説明がありますが、requiredRevisionIdとtargetRevisionIdにフォームのリビジョンIDを指定します。
requiredRevisionIdは、フォームの最新のリビジョンでない場合、リクエストは処理されず、400の不正なリクエストエラーが返されます。
targetRevisionIdは、最新のリビジョンを指定しなくても良いのですが、最新のリビジョンよりも大幅に遅れている場合、要求は処理されず、400の不正なリクエストエラーが返されます。
指定したリビジョンの後に変更が発生した場合、フォームの更新はその変更に対して行われるようです(競合を解決するとのこと)
リクエスト本文の例)
新規に作成したフォームから、上記のようなアイテムを追加していきます。
以下のJSONがフォームの説明を更新、フォームのアイテムを追加する時の例です。
{
"requests": [
{
"createItem": {
"item": {
"title": "初めてのご注文ですか",
"questionItem": {
"question": {
"choiceQuestion": {
"type": "RADIO",
"options": [
{
"value": "初"
},
{
"value": "以前にある"
}
]
}
}
}
},
"location": {
"index": 0
}
}
},
{
"createItem": {
"item": {
"title": "どのアイテムをご希望ですか",
"questionItem": {
"question": {
"required": true,
"textQuestion": {}
}
}
},
"location": {
"index": 1
}
}
},
{
"createItem": {
"item": {
"title": "ご希望の色をお選びください",
"questionItem": {
"question": {
"choiceQuestion": {
"type": "CHECKBOX",
"options": [
{
"value": "赤"
},
{
"value": "青"
},
{
"value": "白"
},
{
"value": "カーキ"
}
]
}
}
}
},
"location": {
"index": 2
}
}
},
{
"updateFormInfo": {
"info": {
"description": "これはサンプルフォームです。回答のテストもしますが、すぐに削除しますよ。"
},
"updateMask": "description"
}
}
],
"writeControl": {
"targetRevisionId": "00000002"
}
}
createItemでフォームの項目を追加、updateFormInfoでフォームの説明欄を更新しています。
レスポンス本文例)
成功時のAPIの実行結果は以下のようになります。
{
"replies": [
{
"createItem": {
"itemId": "3a189186",
"questionId": [
"6a401f94"
]
}
},
{
"createItem": {
"itemId": "47aa5aba",
"questionId": [
"09f771e6"
]
}
},
{
"createItem": {
"itemId": "5687af5a",
"questionId": [
"2063e2c0"
]
}
},
{}
],
"writeControl": {
"requiredRevisionId": "00000005"
}
}
既存のアイテムを更新する場合は、 itemIdやquestionIdを指定して行なっていくことになります。
さいごに
Google Forms APIを使ってフォームの作成を行いました。 単発で作成するならわざわざAPIを使う必要はないかと思いますが、自社で持っているデータ(顧客データや製品に関する質問を溜め込んだデータなど)を活用して自動的にアンケートフォームやクイズを作る といった時に重宝しそうですね。 今回は触れていませんが、回答のデータを利用してリアルタイムのダッシュボードを作ったり、回答の履歴を１箇所で確認したりするといったこともできそうなので別の記事にて記載しようかと思います。
